

package android.os;

/**
 * 可以将实例写入并从{@link Parcel}中恢复的类的接口。
 * 实现Parcelable接口的类还必须有一个名为CREATOR的静态字段，
 * 它是一个实现了{@link Parcelable.Creator Parcelable.Creator} 的接口。
 * 
 * <p>Parcelable的典型实现是:</p>
 * 
 * <pre>
 * public class MyParcelable implements Parcelable {
 *     private int mData;
 *
 *     public int describeContents() {
 *         return 0;
 *     }
 *
 *     public void writeToParcel(Parcel out, int flags) {
 *         out.writeInt(mData);
 *     }
 *
 *     public static final Parcelable.Creator&lt;MyParcelable&gt; CREATOR
 *             = new Parcelable.Creator&lt;MyParcelable&gt;() {
 *         public MyParcelable createFromParcel(Parcel in) {
 *             return new MyParcelable(in);
 *         }
 *
 *         public MyParcelable[] newArray(int size) {
 *             return new MyParcelable[size];
 *         }
 *     };
 *     
 *     private MyParcelable(Parcel in) {
 *         mData = in.readInt();
 *     }
 * }</pre>
 */
public interface Parcelable {
    /**
     * Flag for use with {@link #writeToParcel}: the object being written is a return value,
     * that is the result of a function such as
     * "Parcelable someFunction()</code>",
     * "void someFunction(out Parcelable)</code>", or
     * "void someFunction(inout Parcelable)</code>".
     * Some implementations may want to release(释放) resources at this point.
     * parcelable write return value
     */
    public static final int PARCELABLE_WRITE_RETURN_VALUE = 0x0001;
    
    /**
     * Bit masks（位掩码） for use with {@link #describeContents}:
     * each bit represents a kind of object considered（备被考虑的） to have potential（潜在） special（特殊） significance（意义） when marshalled（整理）.
     * 每个比特代表一种在编组时被认为具有潜在特殊意义的对象。
     * contents file descriptor(描述)
     */
    public static final int CONTENTS_FILE_DESCRIPTOR = 0x0001;
    
    /**
     * Describe the kinds of special objects contained in this Parcelable's marshalled representation（代表）.
     *  描述包含在这个Parcelable的编组表示中的特殊对象。
     * @return a bitmask indicating （表明）the set of special object types marshalled by the Parcelable.
     * 指示由Parcelable编组的特殊对象类型集合的位掩码。
     */
    public int describeContents();
    
    /**
     * Flatten（击倒，平铺） this object in to a Parcel.
     * 将这个对象平铺到一个包裹中。
     * 
     * @param dest： The Parcel in which the object should be written.
     * @param flags： Additional（额外的） flags about how the object should be written.
     * May be 0 or {@link #PARCELABLE_WRITE_RETURN_VALUE}.
     */
    public void writeToParcel(Parcel dest, int flags);

    /**
     * Interface that must be implemented and provided as a public CREATOR
     * field that generates（生成） instances of your Parcelable class from a Parcel.
     */
    public interface Creator<T> {
        /**
         * Create a new instance of the Parcelable class,
         * instantiating （实例化）it from the given Parcel whose data had previously（预先） been written by
         * {@link Parcelable#writeToParcel Parcelable.writeToParcel()}.
         * 
         * @param source The Parcel to read the object's data from.
         * @return Returns a new instance of the Parcelable class.
         */
        public T createFromParcel(Parcel source);
        
        /**
         * Create a new array of the Parcelable class.
         * 
         * @param size Size of the array.
         * @return Returns an array of the Parcelable class, with every entry initialized to null.
         * 返回Parcelable类的数组，每个条目初始化为null。
         */
        public T[] newArray(int size);
    }

    /**
     * Specialization（专业化） of {@link Creator} that allows you to receive the ClassLoader the object is being created in.
     * 允许您接收正在创建对象的ClassLoader。
     */
    public interface ClassLoaderCreator<T> extends Creator<T> {
        /**
         * Create a new instance of the Parcelable class, instantiating it
         * from the given Parcel whose data had previously been written by
         * {@link Parcelable#writeToParcel Parcelable.writeToParcel()} and
         * using the given ClassLoader.
         *
         * @param source The Parcel to read the object's data from.
         * @param loader The ClassLoader that this object is being created in.
         * @return Returns a new instance of the Parcelable class.
         */
        public T createFromParcel(Parcel source, ClassLoader loader);
    }
}
